Rail Availability
The Rail Availability request returns schedules and/or fares for a specific journey plan. The default search is 'fastest journey' for 'all classes'. The response can include all journey legs with departure and arrival date and times, fares, and commercial offers.
Note: At this time, only one-way or round-trip journeys are supported via the Rail Availability Search or Low Fare Shopping request.
A commercial offer consists of a price (made up of one or more fares) and an itinerary (both directions, for a round-trip journey), where the price and itinerary have been cross-checked against each other. RCS does not apply any commercial "best buy" logic or any filtering to the responses it receives from rail suppliers (e.g., to identify the lowest fares).
If the client requests both schedules and fares, then the service provides information about schedule and fare combinations (considering both the fare rules and the availability of the fare on specific services).
Available Suppliers (Distributors)
See RCS Distributor Content Functionality for a list and functional descriptions of currently supported RCS rail suppliers.
Request
RailAvailabilitySearchReq is used to request rail searches.
Minimum Data
SearchRailLeg contains the time and location data for one or more legs to be searched. The minimum required data for a Rail Search request are:
-
Origin location. Origin and destination data must be supplied in normalized form for Universal API. Reference Data can be used to obtain the normalized form if required. Include RailLocation in SearchOrigin or SearchDestination to search for a specific train station.
-
Destination location (supplied in the same format as the origin location).
-
Type of journey (one-way or round-trip).
-
Departure date/time of outbound journey.
-
Departure date/time of inbound journey (if applicable).
-
Number of passengers (defaults to one adult passenger). See Rail Availability with Passenger Type for information about different passenger types.
For the SearchOrigin and SearchDestination elements:
- IATA Codes can be sent in the Airport, City, and CityOrAirport attributes.
- UCodes and TCodes can be sent in the RailLocation attribute.
-
With Air.xsd, shopping for rail fares using TCodes and UCodes is available in Rail LowFareSearchReq and LowFareSearchAsynchReq (v49.0 and earlier).
Optional Data
If not indicated in the request,for the ResponseType element:
- “Fares” is mapped if the request is for a specific rail segments.
- “Availability” is default if Fares is unmapped.
- When the ResponseType is "Schedules", journey and sometimes passenger information (depending on the rail distributor) are returned in the response.
Discount and/or Loyalty cards may be sent in a RailAvailability request, and in the RailCreateReservation request. If the vendor does not support discount or loyalty cards, a warning is returned. The list of valid codes is obtained using the TypeCode="RailDiscountLoyalty" in the ReferenceDataRetrieve utility. For example: util:ReferenceDataRetrieveReq/@TypeCode. See the Exceptions section below for supplier-specific information.
The Loyalty Card is required if a loyalty membership number is used. Requires the supplier (vendor) code and member number.
Note: When a RailCreateReservationReq is sent with an existing Universal Record locator code and the BookingTraveler name in the new booking is the same as the BookingTraveler name in the UR, the MembershipProgram and CardNumber attributes in LoyaltyCard are added to the BookingTraveler in the UR. A new BookingTraveler element is not created. If the BookingTraveler LoyaltyCard information is the same as the information in the UR, the MembershipProgram and CardNumber are not added to the BookingTraveler in the UR.
Second Availability Request
A second Rail Availability request can be sent with the following data to request fares for specified train segments:
- ResponseType="Fares"
-
Host Token for each selected rail segment (found in the Rail Journey element in the previous Rail Availability response).
This functionality is provided for rail distributors that recommend a second Rail Availability or Exchange Quote request to confirm fares as part of their business processes. Currently, Amtrak offers this functionality.
Notes:
-
When an initial shop request returns the alert “Prices are for one adult” in the response, a second RailAvailabilityReq should be sent using selected train segments to obtain accurate prices.
- Some suppliers can return over 2,000 commercial offers in a response. /RailSearchModifiers MaxSolutions is used to limit the number of solutions returned in the shop response.
Modifiers
In addition to the minimum required data, modifiers can be added to the request to further define the search criteria.
Response
RailAvailabilitySearchRsp returns options for a requested Rail Availability.
A successful rail shop response includes the following information:
-
Itineraries are included in the RailJourneyList.
-
Fares are included in the RailPricingSolution and reference the itineraries in RailJourneyList. The TotalPrice is the total amount, including taxes and fees, for all passengers on all segments. However, seat reservation costs, if any, are not included in TotalPrice.
Note: If the rate is not in the agency's default currency, Universal API provides an ApproximateTotalPrice amount at the RailPricingInfo level in the agency's default currency.
-
Fare rules are provided in the RailFareNoteList.
-
Various additional information, such as flexibility levels and vendor specific passenger types (VendorPaxType), is provided in the RailFareIDList.
If a RailLocation is sent in SearchOrigin and RCS does not return an IATA Code or UCode/TCode, the response returns a warning message: A successful rail shop response has been returned by the rail distributor. However, the rail distributor did not return one or more origin and/or destination location codes.
If RCS does not return FareClass in the response, CabinClass="Economy" will be mapped. In older schemas, CabinClass= "Standard" is mapped.
Universal API maps the TrainServiceType value to the RailSegment attribute TrainTypeCode and the Description to the TrainType attribute. If the value sent by RCS in TrainServiceType is not found, the value of "UNKNOWN" is returned in the TrainType attribute. In older schemas, if 7.TNP thru 63.TNP are returned by RCS, Univeral API maps "UNKNOWN" in TrainType.
OperatingCompanyIf an unknown rail supplier is returned in the Rail Availability search response, OperatingCompany @Name is indicated as "OperatingCompanyUnknown". This value is equivalent to the RCS code 0.ROP.
FulfillmentTypeFulfillment options available in the Rail Availability search response include: Ticket on Departure, Ticketless, Ticket By Email, and Travel Agency. These options were added in Air v32.0 to LowFareSearchRsp.
Fulfillment options in the response can be associated to either the segment (RailSegment) or the fare (RailFare). In some cases, different fulfillment options may be returned in RailSegment/FulfillmentType and RailFare/FulfillmentType. If different options are returned, the value in RailFare/Fulfillment should be used for the subsequent Rail Booking request (RailCreateReservationReq).
FulfillmentTypeFulfillment options available in the Rail Availability search response include: Ticket on Departure, Ticketless, Ticket By Email, and Travel Agency. These options were added in Air v32.0 to LowFareSearchRsp.
Fulfillment options in the response can be associated to either the segment (RailSegment) or the fare (RailFare). In some cases, different fulfillment options may be returned in RailSegment/FulfillmentType and RailFare/FulfillmentType. If different options are returned, the value in RailFare/Fulfillment should be used for the subsequent Rail Booking request (RailCreateReservationReq).
Reservation Required
Some rail suppliers require seat reservations to confirm a booking. In RailSegment, if ReservationRequired="true," then a reservation is required for the selected journey. The traveler must book the journey with the supplier.
Errors and Warnings
An unsuccessful Rail Availability response includes either:
-
An error from RCS, or
-
An error from the supplier
Possibly one or more warnings may display that certain request criteria were not passed to a supplier (typically because the supplier does not support the specified criterion).
If the schema only supports FareReference with "StringLength1to8" and the FareReference value returned by RCS is larger than eight characters, the FareReference value is truncated. The booking does not fail, but a warning message is returned in the response: The RailFare @ FareReference value has been truncated. The complete FareReference value is #.", where # is the complete FareReference value.
Exceptions
The rail segments that are returned may be different than the one sent in the shop request. For example, if the shop request is for an adult and child, but the rail segment sent is only valid for adult travelers, Amtrak will return rail segment(s) in the shop response that are valid for both adult and child. A warning is also sent in the response: "Outward / Return journey is an alternate to the originally requested journey".
-
Previously, Discount Codes sent for Amtrak in the Rail Booking request were ignored and booked without the discount code applied.
- With Rail v32.0, the Discount Code can be applied to the booking. The response returns the discounted fare.
- Only one Discount Code is supported for the Rail Booking request. If there are multiple Discount Codes in the Rail Booking request, Amtrak processes only the first code.
- Support for discount codes varies supplier.
-
With Rail v33.0, six new DiscountCodes are added for Amtrak. The two military discount codes do not require a member number as the traveler will be asked for an active-duty ID card by the train conductor:
-
Code="291.DIS" for Military traveller
-
Code="292.DIS" for Military Child
-
Code="293.DIS" for AAA Adult and requires AAA membership number
-
Code="295.DIS" for AAA Child and requires AAA membership number
-
Code="296.DIS" for NARP and requires National Association of Railroad Passengers membership number
-
Code="297.DIS" for Veterans Advantage and requires a membership number
-
- The
Corporate Discount or Promotion Code is associated with the Booking Traveler
in the RailCreateReservationReq. The Corporate Discount or Promotion Code
returned by Amtrak in the second shop response (see Amtrak
Exceptions in Rail Availability) should be sent for one passenger in a single-
or multi-passenger book request.
- If multiple Corporate Discount or Promotion Codes with: different Reference values are sent for one passenger in a single- or multi-passenger booking, each will be mapped to RCS at booking level.
- If multiple Corporate Discount or Promotion Codes with the same Reference values are sent for one passenger in a single- or multi-passenger booking, the Corporate Discount or Promotion Code is mapped once at booking level.
- If multiple Corporate Discount or Promotion Codes with different Reference values are sent for multiple Booking Travelers, all of them are mapped to RCS at booking level.
- If multiple Corporate Discount or Promotion Codes with the same Reference values are sent for multiple Booking Travelers, the Corporate Discount or Promotion Code is mapped once at booking level.
- Amtrak requires that the Corporate Discount or Promotion Code card number is sent in the request. Other rail distributors do not require the card number.
Currently, SNCF is the only supplier that supports refundable and exchangeable rail fares for Rail Availability searches.